home *** CD-ROM | disk | FTP | other *** search
/ PsL Monthly 1993 December / PSL Monthly Shareware CD-ROM (December 1993).iso / prgmming / dos / c / lib_dos.exe / WI.DOC < prev    next >
Encoding:
Text File  |  1991-05-26  |  24.0 KB  |  647 lines
  1. -------------------------[ WI.LIB ]----------for DOS---------------------------
  2.                       WI.LIB - Wilkes Index Library
  3.                     Copyright (c) 1989 by Roger Wilkes
  4.            Member: Association of Shareware Professionals (ASP)
  5.                   Cost of this Software $40; Gov./Ed. $30
  6.                         Wilkes Software, inc.
  7.                         Memphis, TN 38134
  8.                     or Register on BBS at (901)377-5608
  9. -------------------------------------------------------------------------------
  10.  
  11.     There are a total of six (6) function calls available with this library.
  12. 1) IX_add        - to add keys to an index file
  13. 2) IX_del        - to delete keys from an index file
  14. 3) IX_find_first - to find the first key which meets comparison criteria
  15. 4) IX_find_last  - to find the last key which meets comparison criteria
  16. 5) IX_find_next  - to find the next key
  17. 6) IX_find_prev  - to find the previous key
  18.  
  19. -------------------------------------------------------------------------------
  20.  
  21.     You must insure that "WI.LIB" is available to the linker at link time.
  22. WI.LIB is to be linked with Microsoft large (-AL) and huge (-AH) memory
  23. models.
  24.  
  25.     Place WI.LIB in your LIB directory and place INDEX.H in your INCLUDE
  26. directory.
  27.  
  28.     The maximum char array key length is 127.  All data types other than this
  29. one can use the "data_type" defines (see INDEX.H).  The character array
  30. data type is formed by anding the length and 0x80.
  31.  
  32. -------------------------------------------------------------------------------
  33.  
  34. 1) Adding a new key to the index file:
  35.    Indexing/Reindexing a file:
  36.  
  37.     int IX_add (long            file_pos,
  38.                 char            *key_addr,
  39.                 unsigned char   data_type,
  40.                 int             file_handle);
  41.  
  42.     file_pos      - is the piece of data which will accompany the key.  This
  43.                     information will be returned to you when you use the
  44.                     IX_find_xxxxx function calls.  If you are working with
  45.                     fixed length records this can be a record length.  If you
  46.                     use this field to contain a record number, you will have
  47.                     to do multiplications to get it to a byte position within
  48.                     the file you are indexing.  You may simply use this field
  49.                     to contain the byte position of the record being indexed.
  50.     key_addr      - contains the address of either
  51.                     1) the key data
  52.                     2) a KEY_STRUCT (see INDEX.H) structure containing up to
  53.                        10 key parts.  The order of importance of the key
  54.                        fields is from lowest index to highest (i.e.
  55.                        KEY_COMPONENT.key[0] to KEY_COMPONENT.key[9]).
  56.     data_type     - specifies that the "key_value" above is either key data
  57.                     or a KEY_STRUCT structure (see INDEX.H).  If data_type
  58.                     designates key data, the length (in bytes) is also known.
  59.  
  60.     RETURNS:    One of the function returns shown in INDEX.H
  61.                     OK          where no errors were detected
  62.                     IX_IO_ERR
  63.                     IX_ERR
  64.                     INV_PARAM
  65.                     INV_NUM_KEYS
  66.  
  67.     EXAMPLE:    if we have a file with the following record layout which we
  68.                 wish to index on the last_name
  69.  
  70. -------------------------------------------------------------------------------
  71.     /* using the Microsoft "C" Optimizing compiler */
  72. #include <index.h>      /* after placing in include dir */
  73. #include <fcntl.h>
  74. #include <sys\types.h>
  75. #include <sys\stat.h>
  76. #include <io.h>
  77. #include <stdlib.h>
  78. #include <stdio.h>
  79.  
  80. #define TRUE        1
  81. #define FALSE       0
  82.  
  83. int nad_file;
  84. int index_file;
  85.  
  86. int num_bytes;
  87. int err;
  88. long file_pos = 0L;
  89.  
  90. struct {
  91.     char        first_name [15];
  92.     char        last_name [15];
  93.     char        addr [30];
  94.     char        city [20];
  95.     char        state [2];
  96.     char        zip [9];
  97. } name_and_addr;
  98.  
  99. main ()
  100. {
  101.     if ((nad_file = open ("nameaddr.fil", O_CREAT | O_BINARY | O_RDWR,
  102.                           S_IREAD | S_IWRITE)) == -1)
  103.     {
  104.        /* do something about the error */
  105.     }
  106.     if ((index_file = open ("nameaddr.inx", O_CREAT | O_BINARY | O_RDWR,
  107.                            S_IREAD | S_IWRITE)) == -1)
  108.     {
  109.       /* do something about the error */
  110.     }
  111.     while (TRUE)
  112.     {
  113.         num_bytes = read (nad_file, (char *)&name_and_addr,
  114.                           sizeof(name_and_addr));
  115.         if (num_bytes == 0)     /* end of file */
  116.             break;
  117.         if (num_bytes != sizeof(name_and_addr))
  118.         {
  119.            /* take care of short read */
  120.         }
  121.         err = IX_add (file_pos, name_and_addr.last_name,
  122.                       sizeof(name_and_addr.last_name)+0x80, index_file);
  123.                    /* 0x80 is simply the high order bit
  124.                       of the data_type.  For all other data
  125.                       types you can use the #define names
  126.                       (see INDEX.H) */
  127.         switch (err)
  128.         {
  129.             case OK:
  130.                 printf ("NAME: %15.15s indexed\n",
  131.                         name_and_addr.last_name);
  132.                 break;
  133.             case IX_IO_ERR:
  134.                 printf ("IO Error on \"nameaddr.inx\" file\n");
  135.                 break;
  136.             case IX_ERR:
  137.                 printf ("Index File is corrupted\n");
  138.                 break;
  139.             case INV_PARAM:
  140.                 printf ("Function Call Parameters don't match\n");
  141.                 printf (" information already in \"nameaddr.inx\"\n");
  142.                 break;
  143.             case INV_NUM_KEYS:
  144.                 printf ("The number of key fields does not match\n");
  145.                 printf (" information already in \"nameaddr.inx\"\n");
  146.                 break;
  147.             default: break;
  148.         }
  149.         if (err)
  150.             break;
  151.         file_pos += sizeof(name_and_addr);
  152.     }
  153. }
  154. -------------------------------------------------------------------------------
  155.  
  156. 2) Deleting an index entry from an index file:
  157.  
  158.     int IX_del (char            *key_addr,
  159.                 long            file_pos,
  160.                 unsigned char   data_type,
  161.                 int             file_handle);
  162.  
  163.     key_addr      - contains the address of either
  164.                     1) the key data
  165.                     2) a KEY_STRUCT (see INDEX.H) structure containing up to
  166.                        10 key parts.  The order of importance of the key
  167.                        fields is from lowest index to highest (i.e.
  168.                        KEY_COMPONENT.key[0] to KEY_COMPONENT.key[9]).
  169.     file_pos      - is the piece of data which will accompany the key.  This
  170.                     information will be returned to you when you use the
  171.                     IX_find_xxxxx function calls.  If you are working with
  172.                     fixed length records this can be a record length.  If you
  173.                     use this field to contain a record number, you will have
  174.                     to do multiplications to get it to a byte position within
  175.                     the file you are indexing.  You may simply use this field
  176.                     to contain the byte position of the record being indexed.
  177.                     The file position field is required in the delete to
  178.                     differentiate between duplicate keys and must be the same
  179.                     as used during IX_add.
  180.     data_type     - specifies that the "key_value" above is either key data
  181.                     or a KEY_STRUCT structure (see INDEX.H).  If data_type
  182.                     designates key data, the length (in bytes) is also known.
  183.  
  184.     RETURNS:    One of the function returns shown in INDEX.H
  185.                     OK          where no errors were detected
  186.                     IX_IO_ERR
  187.                     IX_ERR
  188.                     INV_PARAM
  189.                     INV_NUM_KEYS
  190.  
  191.     EXAMPLE:    if we have a file with the following record layout which we
  192.                 wish to delete all indexes from.  NOTE: we could accomplish
  193.                 the same thing, in this case, by deleting the file; except
  194.                 here, the file size will not change (i.e. not be clean).
  195.  
  196. -------------------------------------------------------------------------------
  197.     /* using the Microsoft "C" Optimizing compiler */
  198. #include <index.h>      /* after placing in include dir */
  199. #include <fcntl.h>
  200. #include <sys\types.h>
  201. #include <sys\stat.h>
  202. #include <io.h>
  203. #include <stdlib.h>
  204. #include <stdio.h>
  205.  
  206. #define TRUE        1
  207. #define FALSE       0
  208.  
  209. int nad_file;
  210. int index_file;
  211.  
  212. int num_bytes;
  213. int err;
  214. long file_pos = 0L;
  215.  
  216. struct {
  217.     char        first_name [15];
  218.     char        last_name [15];
  219.     char        addr [30];
  220.     char        city [20];
  221.     char        state [2];
  222.     char        zip [9];
  223. } name_and_addr;
  224.  
  225. main ()
  226. {
  227.     if ((nad_file = open ("nameaddr.fil", O_CREAT | O_BINARY | O_RDWR,
  228.                           S_IREAD | S_IWRITE)) == -1)
  229.     {
  230.        /* do something about the error */
  231.     }
  232.     if ((index_file = open ("nameaddr.inx", O_CREAT | O_BINARY | O_RDWR,
  233.                             S_IREAD | S_IWRITE)) == -1)
  234.     {
  235.       /* do something about the error */
  236.     }
  237.     while (TRUE)
  238.     {
  239.         num_bytes = read (nad_file, (char *)&name_and_addr,
  240.                           sizeof(name_and_addr));
  241.         if (num_bytes == 0)     /* end of file */
  242.             break;
  243.         if (num_bytes != sizeof(name_and_addr))
  244.         {
  245.             /* take care of short read */
  246.         }
  247.         err = IX_del (name_and_addr.last_name, file_pos,
  248.                       sizeof(name_and_addr.last_name)+0x80, index_file);
  249.                    /* 0x80 is simply the high order bit
  250.                       of the data_type.  For all other data
  251.                       types you can use the #define names
  252.                       (see INDEX.H) */
  253.         switch (err)
  254.         {
  255.         case OK:
  256.             printf ("NAME: %15.15s index Deleted\n",
  257.                     name_and_addr.last_name);
  258.             break;
  259.         case IX_IO_ERR:
  260.             printf ("IO Error on \"nameaddr.inx\" file\n");
  261.             break;
  262.         case IX_ERR:
  263.             printf ("Index File is corrupted\n");
  264.             break;
  265.         case INV_PARAM:
  266.             printf ("Function Call Parameters don't match\n");
  267.             printf (" information already in \"nameaddr.inx\"\n");
  268.             break;
  269.         case INV_NUM_KEYS:
  270.             printf ("The number of key fields does not match\n");
  271.             printf (" information already in \"nameaddr.inx\"\n");
  272.             break;
  273.         default: break;
  274.         }
  275.         if (err)
  276.             break;
  277.         file_pos += sizeof(name_and_addr);
  278.     }
  279. }
  280. -------------------------------------------------------------------------------
  281.  
  282. 3) Finding indexed keys in an index file:
  283.  
  284.     int IX_find_first (FIND_IX          *fix,
  285.                        char             *key_addr,
  286.                        int              find_condition,
  287.                        int              file_handle,
  288.                        unsigned char    data_type);
  289.  
  290.     int IX_find_last  (FIND_IX          *fix,
  291.                        char             *key_addr,
  292.                        int              find_condition,
  293.                        int              file_handle,
  294.                        unsigned char    data_type);
  295.  
  296.     int IX_next       (FIND_IX          *fix);
  297.  
  298.     int IX_prev       (FIND_IX          *fix);
  299.  
  300.     fix           - is the address of the FIND_IX structure
  301.                     typedef struct
  302.                     {
  303.                         long            data_rec;   /* returned file pos */
  304.                         long            recno[3];   /* used internally */
  305.                         int             ix[3];      /* used internally */
  306.                         unsigned char   data_type;  /* used internally */
  307.                         unsigned char   find_type;  /* used internally */
  308.                         VALUE           *val        /* used internally */
  309.                         int             fn;         /* used internally */
  310.                     } FIND_IX;
  311.                     the data_rec field contains the file position of the
  312.                     indexed file, in order to locate the proper record.
  313.     key_addr      - contains the address of either
  314.                     1) the key data
  315.                     2) a KEY_STRUCT (see INDEX.H) structure containing up to
  316.                        10 key parts.  The order of importance of the key
  317.                        fields is from lowest index to highest (i.e.
  318.                        KEY_COMPONENT.key[0] to KEY_COMPONENT.key[9]).
  319.                     You must insure that the value this address points to
  320.                     does not change between IX_find_first/IX_find_last
  321.                     calls and IX_find_next/IX_find_prev calls.
  322.     find_condition- is one of the file conditions listed in INDEX.H
  323.                     1) FIND_EQL
  324.                     2) FIND_GTR
  325.                     3) FIND_LSS
  326.                     4) FIND_NEQ
  327.                     5) FIND_GEQ
  328.                     6) FIND_LEQ
  329.     file_handle   - is the file number of the open file in which the indexes
  330.                     will be found.
  331.     data_type     - specifies that the "key_value" above is either key data
  332.                     or a KEY_STRUCT structure (see INDEX.H).  If data_type
  333.                     designates key data, the length (in bytes) is also known.
  334.  
  335.     EXAMPLE:    if we have a file with the following record layout which we
  336.                 wish find and print all records where the last name is
  337.                 greater than or equal to "Marty" - remember that upper and
  338.                 lower case are different:
  339.  
  340. -------------------------------------------------------------------------------
  341.     /* using the Microsoft "C" Optimizing compiler */
  342. #include <index.h>      /* after placing in include dir */
  343. #include <fcntl.h>
  344. #include <sys\types.h>
  345. #include <sys\stat.h>
  346. #include <io.h>
  347. #include <stdlib.h>
  348. #include <stdio.h>
  349.  
  350. #define TRUE        1
  351. #define FALSE       0
  352.  
  353. int nad_file;
  354. int index_file;
  355.  
  356. int num_bytes;
  357. int err;
  358. long file_pos = 0L;
  359. FIND_IX fix;
  360. char *compare_field = "Marty          ";
  361.  
  362. struct {
  363.     char        first_name [15];
  364.     char        last_name [15];
  365.     char        addr [30];
  366.     char        city [20];
  367.     char        state [2];
  368.     char        zip [9];
  369. } name_and_addr;
  370.  
  371. main ()
  372. {
  373.     if ((nad_file = open ("nameaddr.fil", O_RDONLY | O_BINARY)) == -1)
  374.     {
  375.        /* do something about the error */
  376.     }
  377.     if ((index_file = open ("nameaddr.inx", O_RDONLY | O_BINARY)) == -1)
  378.     {
  379.        /* do something about the error */
  380.     }
  381.  
  382.     err = IX_find_first (&fix, compare_field,
  383.                          FIND_GEQ, index_file,
  384.                          sizeof(name_and_addr.last_name)+0x80);
  385.     while (TRUE)
  386.     {
  387.         switch (err)
  388.         {
  389.         case OK:
  390.             lseek (nad_file, fix.data_rec, SEEK_SET);
  391.             num_bytes = read (nad_file, (char *)&name_and_addr,
  392.                               sizeof(name_and_addr));
  393.             if (num_bytes != sizeof(name_and_addr))
  394.             {
  395.                 /* take care of short read */
  396.             }
  397.             printf ("NAME: %15.15s %15.15s | CITY/ST: %20.20s %2.2s\n",
  398.                     name_and_addr. first_name,
  399.                     name_and_addr. last_name,
  400.                     name_and_addr. city,
  401.                     name_and_addr. state);
  402.             break;
  403.         case IX_IO_ERR:
  404.             printf ("IO Error on \"nameaddr.inx\" file\n");
  405.             break;
  406.         case IX_ERR:
  407.             printf ("Index File is corrupted\n");
  408.             break;
  409.         case NOT_FOUND:
  410.             printf ("No Matching Keys Found\n");
  411.             break;
  412.         case NO_MORE:
  413.             printf ("No More Matching Keys Found\n");
  414.             break;
  415.         case INV_PARAM:
  416.             printf ("Function Call Parameters don't match\n");
  417.             printf (" information already in \"nameaddr.inx\"\n");
  418.             break;
  419.         case INV_NUM_KEYS:
  420.             printf ("The number of key fields does not match\n");
  421.             printf (" information already in \"nameaddr.inx\"\n");
  422.             break;
  423.         default: break;
  424.         }
  425.         if (err)
  426.             break;
  427.         err = IX_find_next (&fix);
  428.     }
  429. }
  430. -------------------------------------------------------------------------------
  431.  
  432. 4) Data Types:
  433.  
  434.     #define             "C"
  435.     -------             ---
  436.     ftCHAR              char
  437.     ftUCHAR             unsigned char
  438.     ftSCHAR             signed char
  439.     ftUNS_INT           unsigned int
  440.     ftINT               int
  441.     ftULONG             unsigned long
  442.     ftLONG              long
  443.     ftFLOAT             float
  444.     ftDOUBLE            double
  445.     ftH_BCD_1 - 10      -------         1 to 10 char BCD field with
  446.                                         sign at front of field
  447.     ftT_BCD_1 - 10      -------         1 to 10 char BCD field with
  448.                                         sign at end of field
  449.     ftSTRUCT            -------         multi field key where the
  450.                                         location of the fields is
  451.                                         specified in the KEY_STRUCT
  452.                                         structure (see INDEX.H)
  453. -------------------------------------------------------------------------------
  454.  
  455. 5) KEY_STRUCT structure for multi-field keys:
  456.  
  457.     typedef struct
  458.     {
  459.         unsigned char       num_keys;
  460.         struct
  461.         {
  462.             unsigned char   data_type;      /* data_type for this field */
  463.             VALUE           *val;           /* addr of this key field */
  464.         } key [10];
  465.     } KEY_STRUCT;
  466.  
  467.     If we wish to take the following record layout and index it on
  468. last_name and first_name (in that order):
  469.  
  470.     struct {
  471.         char        first_name [15];
  472.         char        last_name [15];
  473.         char        addr [30];
  474.         char        city [20];
  475.         char        state [2];
  476.         char        zip [9];
  477.     } name_and_addr;
  478.  
  479. with
  480.  
  481.     KEY_STRUCT      keys;
  482.  
  483. the keys would populated as follows:
  484.  
  485.     keys. num_keys = 2;
  486.     keys. key [0]. data_type = sizeof(name_and_addr.last_name) | 0x80;
  487.     keys. key [0]. val = (VALUE *)name_and_addr.last_name;
  488.     keys. key [1]. data_type = sizeof(name_and_addr.first_name) | 0x80;
  489.     keys. key [1]. val = (VALUE *)name_and_addr.first_name;
  490.  
  491. the key_addr parameter for the function calls would be "(char *)&keys"
  492. and the data_type parameter to the function calls would be ftSTRUCT.
  493.  
  494. NOTE: that the maximum number of key fields is 10.  This should be enough
  495.     for any reasonable purpose.  If you require more you can stack the
  496.     keys in some instances (char arrays back to back can be considered
  497.     a single field as long as the cumulative sizes are < 128 characters).
  498. -------------------------------------------------------------------------------
  499.  
  500.  
  501.  
  502.  
  503.  
  504.             LICENSE
  505.             -------
  506.  
  507.     Wilkes INDEX, version 1.0, is being distributed under the "shareware" or
  508. user supported concept.  This software is NOT free software.  The use or
  509. reproduction of this software outside of the limits specified in this license
  510. agreement is prohibited.
  511.  
  512.     Non-registered users are granted a limited license to use this software
  513. for a period not to exceed thirty days.  During this period they should test
  514. and evaluate the software to determine if it will meet their needs. The use of
  515. this software beyond this limited time period requires registration.
  516. Non-registered users are not allowed to distribute this software without the
  517. express written permission of Wilkes Software inc.  The only exceptions to this
  518. distribution restriction are SYSOPS of electronic bulletin boards and
  519. distributors of public domain and user supported software.  SYSOPS and
  520. software distributors must abide by the copying restrictions specified below.
  521.  
  522.     Registered users are granted the right to use Wilkes INDEX on only
  523. one computer at any time.  Site licensing agreements are available for
  524. businesses, corporations, and government agencies.  Registered users are also
  525. granted the right to copy and distribute Wilkes INDEX subject to the
  526. following conditions.
  527.  
  528.     Wilkes INDEX must be copied in its original unmodified form.
  529.  
  530.     All of the files must be included in the copy.
  531.  
  532.     Wilkes INDEX may not be distributed in conjunction with any other
  533.     product without the express written consent of Wilkes Software inc.
  534.  
  535.  
  536.  
  537.  
  538.                 WARRANTY
  539.                 --------
  540.  
  541.     Wilkes Software makes no warranty of any kind, express or implied,
  542. including without limitation, any warranties of merchantability and or fitness
  543. for a particular purpose.  Wilkes Software shall not be liable for any
  544. damages, whether direct, indirect, special or consequential arising from a
  545. failure of this software to operate in the manner desired by the user.
  546. Wilkes Software shall not be liable for any damage to data or property which
  547. may be caused directly or indirectly by use of the program.
  548.  
  549.     IN NO EVENT WILL Wilkes Software BE LIABLE TO YOU FOR ANY DAMAGES,
  550. INCLUDING ANY LOST PROFITS, LOST SAVINGS OR OTHER INCIDENTAL OR CONSEQUENTIAL
  551. DAMAGES ARISING OUT OF YOUR USE OR INABILITY TO USE THE PROGRAM, OR FOR ANY
  552. CLAIM BY ANY OTHER PARTY.
  553.  
  554.  
  555.  
  556.  
  557.  
  558.             REGISTRATION FEES
  559.             -----------------
  560.  
  561. The registration fee for Wilkes INDEX, version 1.0, is only $40.00, with
  562. quantity discount for 10 or more copies: $25.00/copy.
  563.  
  564. Government and Education registration fee is only $30.00, with quantity
  565. discount for 10 or more copies: $20.00/copy.
  566.  
  567. You may fill out and return the registration page below or register on-line
  568. at (901)377-5608.
  569.  
  570. Future updates of the site license copy are provided as follows. The first
  571. update is free.   All others $15.00.
  572.  
  573. Prices are for a titled master copy and cover all charges including shipping.
  574. Licensees will be informed when updates become available and given the option
  575. to update at will.  There is NO penalty for skipping updates.
  576.  
  577.  
  578.  
  579.  
  580.  
  581.     If you should require assistance in the use of the Wilkes INDEX, you
  582. may call the WSI BBS at (901)377-5608.
  583.  
  584.     If you like this software please let me know.  If you have enhancements
  585. you would like to see in this software, please let me know those also.  If you
  586. have complaints about the way the Wilkes INDEX functions I would even like to
  587. hear those.
  588.  
  589.     The following is a registration form.  In addition to the licensing use,
  590. I will also use this information to correlate requests for additional
  591. functionality and for Wilkes Software mailing list purpose (only by Wilkes
  592. Software).  When Wilkes Software offers other software into the shareware
  593. system in the future, information will be sent to registered users of the
  594. Wilkes INDEX.  If you register a non-current version I will send the
  595. current version to you.
  596.  
  597.  
  598.  
  599. to: Wilkes Software, inc.
  600.     5231 Longwood Drive
  601.     Memphis, TN  38134
  602.  
  603.  
  604.     Name (first) ____________________  (last) ____________________
  605.  
  606.     Title    ___________________________________
  607.  
  608.     Company  ___________________________________
  609.  
  610.     Address  ___________________________________
  611.  
  612.              ___________________________________
  613.  
  614.     City     _________________________  State  ___  Zip code _______
  615.  
  616.     Where software obtained: ________________________________________
  617.  
  618.     Version of Wilkes INDEX for Microsoft C: 1.0
  619.  
  620.     System: ____________________
  621.  
  622.     DOS Version: _____
  623.  
  624.     Phone: (____) ____ - _____
  625.  
  626.     If Gov./Ed. please specify: _____________________________________
  627.  
  628. COST:
  629.  
  630.     $40/copy; 10+ copies $25/copy
  631.     Gov./Ed. $30/copy; 10+ copies $20/copy
  632.  
  633.     Tennessee Residents: sales tax is 7.75%
  634.  
  635.     # copies _________ x your price: ____________ + TN sales tax __________
  636.  
  637.         = Total _________________
  638.  
  639. METHOD OF PAYMENT:
  640.  
  641.     VISA/MASTERCARD/CHECK: __________
  642.  
  643.     V/MC account #: ___________________________  Expiration Date: _________
  644.  
  645.     Signature: __________________________________________________
  646.  
  647.